home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine CD 1995 / Archive Magazine CD 1995.iso / discs / prog_disc / volume_8 / issue_06 / risc_os / !Help < prev    next >
Encoding:
Text File  |  1988-11-03  |  3.9 KB  |  85 lines
  1. Interactive help system as supported by !Help (0.29)
  2. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3. By default, when Help is started, the interative help session is active, as
  4. shown by the interactive help window being open in the bottom left hand
  5. corner of the screen. To stop Help doing this, use *Set Help$Options ~I. If
  6. this is done, interactive help may be started by clicking on the help icon.
  7.  
  8. Using interactive help requires no intervention on the user's part. The
  9. window can be resized as desired and the text will be reformatted to fit the
  10. new size.
  11.  
  12. For an application to use interactive help, two WIMP messages are employed,
  13. one is used by Help to request the help text and the other is used by the
  14. application to return the text message.
  15.  
  16. To request help, the Help application sends a message of the following form:
  17.  
  18. block+16   &502   indicates request for help
  19.      +20   mouse x co-ordinate
  20.      +24   mouse y co-ordinate
  21.      +28   mouse button state
  22.      +32   window handle (-1 if not over a window)
  23.      +36   icon handle (-1 if not over an icon)
  24.  
  25. The more astute of you will have realised that locations 20 onwards are the
  26. results of using Wimp_GetPointerInfo!
  27.  
  28. The WIMP system will pass this message automatically to the task in charge
  29. of the appropriate window/icon combination. If the application receiving the
  30. message wishes to produce some interactive help, it should respond with the
  31. following message structure:
  32.  
  33. block+16   &503
  34.      +20   help message, terminated by 0
  35.  
  36. The help message may contain any legal printable characters. If the sequence
  37. |M is encountered, this will be treated as a line break and subsequent text
  38. will be printed on the next line in the window.
  39.  
  40. The help application will issue message type &502 every 1/10th of a second
  41. to allow applications such as ArcEdit & ArcDraw to change the help text
  42. according to the current edit mode. To avoid flicker, the display will only
  43. be updated when the returned help string changes.
  44.  
  45. With certain applications, such as the Filer, no interactive help is
  46. supplied and the Help application supplies some default messages in
  47. instances like this.
  48.  
  49. What help should be provided?
  50. -----------------------------
  51.  
  52. The help text may contain printing character codes (including top-bit-set
  53. ones) and also NewLine charactes. It is terminated by a zero character. The
  54. display will split displays at a word boundary (space character) and force a
  55. newline for NewLines. The text should consist of simple complete English
  56. sentences, each starting on a new line and ending with a full stop. The
  57. sentences should usually be simple imperatives or information:
  58.     Click SELECT to set the alarm.
  59.     The pointer is at pixel (47, 215) within the sprite.
  60.     You are in Select mode.
  61.     Click ADJUST to change to Path-edit mode.
  62.     This is the icon for ArcEdit.
  63. In general menu entries need not be mentioned, except when specific menu
  64. entries interact with pointer operations. As a general rule present
  65. information of interest to the beginner near the top, and expert
  66. tips/information lower down.
  67.  
  68. The terms Click, Drag, Choose, Type, Press and Release should be used
  69. consistently. (Click = Press and Release). The menu buttons (SELECT, MENU,
  70. ADJUST) are in capitals, as are key names (e.g. ESC, RETURN, SHIFT, CONTROL,
  71. A, B, F1, COPY). Miss out speedups and shortcuts, just provide enough help
  72. to help the beginner without drowning him/her in information.
  73.  
  74. If you provide interactive help, do so thoroughly. Provide it on
  75. the icon bar, and on the work area of all your windows. If no actions
  76. are possible in a window, just
  77.     This window shows ...
  78. is better than nothing.
  79. You should assume the following abilities of the user:
  80.     He knows what the MENU key is, can navigate menu trees and choose entries
  81.     He knows what the icon bar is
  82.     He knows how to move/size/toggle/close windows, etc.
  83.     He knows what "dragging an icon" means
  84.     He knows what "filling in a field" (writable icon) means
  85.